Technical Note TN2105
Mac OS X 10.3 Navigation Services Changes

目次

Mac OS X 10.3（Panther）では、ナビゲーションシステムに、エンドユーザとデベロッパの双方に関係する多くの変更が加えられました。従来のバージョンとの互換性を最大限に維持するために多くの努力が払われましたが、この互換性は、文書化されているプログラミングインターフェイスを尊重することによってのみ達成されます。ナビゲーションサービス API（アプリケーションプログラミングインターフェイス）は従来と同じですが、新しい実装は正しく使用することが求められます。この文書では、Mac OS X 10.3 におけるナビゲーションサービスの変更点を説明し、互換性のルールを再掲します。

[2004 年 1 月 30 日]



ダイアログ項目ではなくなった

Mac OS X 10.3 では、ナビゲーションサービスのユーザインターフェイスが一から再設計されており、HIView アーキテクチャと合成ウィンドウを利用するようになりました。この再設計による最も重要な影響は、API 名（たとえば、NavCreateGetFileDialog や NavDialogRun など）が示すようにウィンドウそのものは依然としてダイアログでありながら、ナビゲーションサービスの標準の項目がダイアログ項目ではなくなったことです。

アップルでは、ナビゲーションサービスの標準項目がダイアログ項目だった Mac OS X 10.2 およびそれ以前のころも、デベロッパに対し、「Open」、「Save」、「Choose」、「Cancel」などのボタンやほかの要素を含む標準のナビゲーションサービス項目をダイアログマネージャ API で処理せずに、可能な限りナビゲーションサービス API を使用するよう推奨してきました。

ナビゲーションサービスの標準の項目がダイアログ項目でなくなったため、デベロッパがダイアログマネージャ API（たとえば、GetDialogItem や GetDialogItemAsControl など）を使用してナビゲーションサービスの標準の項目を管理するように作成したコードはすべて失敗します。

これらの項目は、依然としてコントロールマネージャ API または HIView API を使用して管理できますが、アップルでは可能な限りナビゲーションサービス API を使用するようお勧めします。たとえば、適切なコントロールを発見的に探し出して EnableControl および DisableControl を使用するのではなく、NavCustomControl に kNavCtlSetActionState メッセージと任意の kNavDontXxxState パラメータを指定することによって標準のボタンを有効または無効にしたり、NavDialogOptions または NavDialogCreationOptions を使用して標準のボタンのラベルを設定するようにします。

また、独自に項目を追加してナビゲーションサービスダイアログを拡張する正しい方法は、EventProc で kNavCBStart メッセージを受け取った場合にのみ、ナビゲーションサービス API の NavCustomControl を使用し、kNavCtlAddControl メッセージまたは kNavCtlAddControlList メッセージを指定します。

アップルでは、ほかのメッセージを処理するとき、および特に kNavCBCustomizxe メッセージを受け取った場合に、コントロールを追加しないよう強くお勧めします（kNavCBCustomize メッセージは、領域のサイズ設定のためにのみ送信され、ナビゲーションサービスウィンドウが存続する間、何度も送信されます）。CountDITL を使用してナビゲーションサービスウィンドウ内の項目の数を数えたり、AutoEmbedControl API を使用して項目を追加したりすることは、どちらも失敗します。

先頭に戻る



カスタム領域

既存のアプリケーションとの互換性を維持するために、ナビゲーションサービスウィンドウのカスタム領域は、依然として非合成ダイアログウィンドウの一部のように動作し、ダイアログマネージャ API は（GetDialogItemAsControl を含め）これらのカスタム項目でも正しく動作するようになっています。正しい項目数を知るには、NavCustomControl に kNavCtlGetFirstControlID メッセージを指定して使用する必要があります。CountDITL に不適切に依存するほかの方法はすべて失敗するからです。

カスタム領域に追加された要素はすべて特別な非合成ユーザペインに埋め込まれます。ユーザペインは非合成型なので、ナビゲーションサービスウィンドウの kWindowCompositingAttribute を確認して合成または非合成に対応する特別なコードを作成するべきではありません。合成カスタム領域が存在しない現時点では、カスタム領域の項目が従来と同じように非合成ウィンドウにあると想定し、ウィンドウ自身の合成機能を使用しないようにします。

カスタム領域は非合成ですが、次のようにすれば、すべてが合成となる将来に備えておけます。

1）背後の項目の消去を避ける（ほとんどの場合、項目を描画することになるので消去の必要はありません）。

2）消去を避けられない場合は、背景ブラシをハードコードせずに、コードの呼び出しの直前にナビゲーションサービスによって設定された正しい背景を適用する SetUpControlBackground を使用します。

3）ウィンドウの可視のコントロール（デベロッパのものを含め）はすべて、ナビゲーションサービスによって描画されるため、カスタム領域にコントロールを明示的に描画しないようにします。

先頭に戻る



nib と DITLS

ナビゲーションサービスウィンドウは nib に基づくようになり（つまり、Interface Builder によって作成され）、DITL またはリソースに基づかなくなりました。カスタム領域は依然として DITL を使用して管理が可能で、NavCustomControl に kNavCtlAddControlList メッセージを指定して追加できますが、デベロッパは NavCustomControl に kNavCtlAddControl メッセージを指定して追加する必要のある nib ベースのカスタム領域を使用することもできます。nib の使用法を示す AddNibToNav というサンプルコードをデベロッパサイトの「Sample Code」のセクションに用意してます。

先頭に戻る



要約

  • ナビゲーションサービス API を使用する方法は、従来どおり、ナビゲーションウィンドウおよびその要素を操作するための推奨される方法です。

  • 非カスタム領域の項目に対してダイアログマネージャ API を使用することは、以前から推奨されておらず、Mac OS X 10.3 ではサポートされていません。

  • 任意の非カスタム領域の項目を対象にコントロールマネージャ API または HIView API を使用することは可能ですが、これらの使用は避けて、できる限りナビゲーションサービス API を使用します。

  • すべてのカスタム領域項目を対象にダイアログマネージャ API、コントロールマネージャ API、HIView API を使用することは従来どおり可能です。